Mac Mania 4/MacMania 4.toast//Multimedia & Desktop/gst-shaw-berry/ShawBerry - Read Me

Text File | 1993-01-26 | 12KB | 264 lines

RELEASE NOTES FOR SHAWBERRY...



The usual white noise...

This software is named after Kip Shaw, for two very good reasons.
First, it was Kip who got me to do it now, rather than later. And,
second, I keep coming up with ideas for software I fully intend to
name after Kip, only to roll those ideas into the burgeoning Shane
the Plane 2.0 specification. I figured I'd better get the job done
now, rather than take the chance of forgetting to do it later.

ShawBerry: Kip and his wife, Faiga, sent our children a load of
wonderful books. Among them was a volume called "Jamberry", by
Bruce Degan, which is great fun to declaim. From there it's not
hard to see how I arrived at this name.

We did this now because PixPex, if used in bulk, can create a very
time-consuming editing problem. We discussed a number of ways
around this, but none of them seemed fully satisfactory to me.
Moreover, none of the stop-gap solutions offered aid for other,
similar problems. So: ShawBerry will not only plug PixPexSpex lines
into a file, it will also deal with a host of other text merging
problems. For example: if you have a spreadsheet PRN file that
comes to you in chunks, you can reassemble the rows to the way they
appear within the spreadsheet. Problems such as these are not
terribly common - but they don't _need_ to be for this software to
save you a whale of a lot of time.

And: the lines are blurring in my work between quick hacks and
serious utilities. This is a serious piece of software, and yet I
knocked it out in a couple of hours at the end of a long and ugly
day. I'm even prouder of myself than normal (grin), and the pains
we've taken to make modeless an essentially modal function help
ShawBerry to live up to its honorable namesake.



ShawBerry: the nitty gritty details...

ShawBerry does this: it merges text from one file into another at
the insertion points you specify. You tell it which file to amend
and which file to take the amendments from. You can control whether
or not the insertion point text is retained or omitted, whether
searchable marks are inserted before and after the amendment text,
and whether or not the amendment is followed by a carriage return.

ShawBerry works by interaction _only._ I much prefer to work by
Drag & Drop, but I saw no fail-safe way for the software to
distinguish the Amend file from the Amendment file. Consequently,
you must specify each one interactively, by means of Standard File
dialogs.

When you hit the Start button, ShawBerry searches within the Amend
file until it finds the first instance of the Insertion point text.
It then "pastes" in the first line of Amendment text, inserting it
_before_ the Insertion point. The the same thing is done for the
second Insertion point found, pasting the second amendment, and so
on, until the Amend file is completed. A new file (BBEdit 2.2, by
default) is written to disk using a name you specify.

ShawBerry works out of one modeless dialog box, plus the menu bar.
About and Quit are familiar to everyone. The Command key
equivalents for Copy, Paste, and Cut work.

At the top of the dialog box is a Text Edit region into which you
specify your Insertion point text. An Insertion point can be up to
254 characters in length. It consists of _string literals,_ that is
literal case-sensitive text characters with no wildcards. However,
two aliases are permitted: ^t (or ^T) to denote a Tab and ^p (or
^P) to denote a Carriage Return. An Insertion point is essentially
a search string, and it must reflect text actually present in the
Amend file. If it is absent, you will get an error message and
you'll have the opportunity to fix the mistake. The best way to
assure fault-free performance is to simply Copy the Insertion point
text from the Amend file and Paste it into ShawBerry.

The "Amend…" button presents a Standard File dialog that you will
use to specify the file into which you will be "pasting"
amendments.

The "Amendment…" button presents a Standard File dialog that you
will use to specify the file from which the amendments will be
"pasted".

In other words: the Amend file is _almost_ the way you want it. The
Amendments file contains correction lines that, when "pasted" into
the Amend file, will fix it in the way that you want. Amendments
are written one to a paragraph. Ideally, there should be a
one-to-one correspondece between Insertion points in the Amend file
and amendment lines in the Amendment file. However: in the name of
modelessness, we are permitting you to proceed even if there are
more of one than the other. If there are extra Insertion points,
nothing will be pasted in. If there are extra amendments, they will
be appended in bulk at the end of the file ShawBerry creates.

Below the Amend button is a radio button group that controls how
the Insertion point text will be handled in the Amend file. If Omit
text is selected, the Insertion point text will be omitted from the
file ShawBerry creates. If Retain text is selected, the Insertion
point text will be output after the amendment, since amendments are
"pasted" in before the Insertion point. Below, we'll talk about how
to take advantage of this switch.

Below the Amendment button are two check boxes which control how
amendments are "pasted" in. If Insert marks is checked, searchable
marks will be inserted immediately before and after the amendment
text. The mark before the amendment is "|[|" (omitting the quote
marks), and the mark after is "|]|". Users of Torquemada's
wildstrings will not need to be told what to do about these, but
I'll be blathering about them later, anyway.

If Strip returns is checked, the trailing carriage return that ends
each amendment line is omitted from the file ShawBerry creates.
Since amendment lines must end in a carriage return, so that
ShawBerry can tell one from the next, we need a way to specify
whether the returns are to be included with the amendment, or if
they're simply there as terminators.

The Quit button is obvious - I hope! (grin)

The Start… button sets the ball in motion. An astounding amount of
error-trapping happens when you hit start, and each error condition
presents a modal dialog telling you what's gone wrong and giving
you a chance to fix it. If you get a message advising you that the
files are too large to fit in the current memory allocation, Quit
from ShawBerry and increase its allocation; ShawBerry will process
arbitrarily large files so long as it has memory enough to fit both
the Amend and Amendment files in RAM simultaneously.

Finally, ShawBerry is 32-bit clean, multi-finder friendly, Apple
Human Interface Guidelines loyal, System 6 or 7 brave,
external-application courteous, and it possesses many other fine
qualities associated with Boy Scouts and software by me.
Incidentally, ShawBerry does _not_ feature the understated yet
strangely exotic Movado Museum watch cursor, since it's too damn
fast to need it. Also incidentally, ShawBerry makes use of
technology that will, someday, make it possible for Torquemada to
run without a watch cursor...



ShawBerry in real life...

I think it might be better if the universe were asequential...

I had to spew out all of the above static in order to get to this
static. The details above make no sense without this as context,
but this context would make no sense without the above details to
refer back to. So: either we rewrite the time functions to permit
optional randomization, or I'm going to have to get someone else to
write docs for me... (grin)

All right, look at it: here's Kip's problem: he has a file of text
that is flagged with text like this: "[PICTURE 1]", "[PICTURE 2]",
"[PICTURE 3]". He want to paste an Xtags picture box specification
in each of those spots. Surprise!: a PixPexSpex… file is a
perfectly formatted Amendment file, as is (assuming he clicked on
the pictures in the right order). So he could do two things:

1. Run a Torquemada set like this

[PICTURE ^#^?]
[PICTURE]

which makes the flags searchably consistent. Then he specifies
"[PICTURE]" as his Insertion point in ShawBerry, hits Omit text,
unchecks Insert marks and checks Strip returns, specifies the
Torqued file as his Amend file and the PixPexSpex… file as his
Amendment file. Presto! Done...

2. Alternatively, he could specify "[PICTURE " as his Insertion
point and run on the _original_ file, with Insert marks checked,
then Torque like this:

|[|^?|]|^*]
^?

to remove the marks and the leftover text.

That's what the marks are for, to make uniquely searchable
Torquemada strings. You can also use them in conjunction with your
word processor to make sure that what you got is what you wanted.

Here's more: in the TorqueManual, I talk about how to take text set
in multiple columns and break it up into one long column. Suppose
you want to do the opposite? Why? Life is like that sometimes. I've
has people send me PRN files from _very_ wide spreadsheet files.
The spreadsheet software would only permit PRN files to be ±140
characters wide, so the spreadsheets would be segmented in vertical
chunks, perfectly useless. I've also had parallel database reports
that needed to be merged into one horizontal line of data. And I've
had situations where lines from separate files needed to be blended
as alternating paragraphs. All of these are duck soup for
ShawBerry.

Take the spreadsheets (please!): the Amend file would be the left
chunk, the Amendment file the next chunk to the right (with the
procedure repeated for any additional chunks). The insertion point
is "^p", the end of the line, soldier. We'll Retain text and Strip
returns, although we could do just the opposite. Better the former
if we Insert marks, as we mght want to do in order to verify and
clean-up the formatting.

And the blended paragraphs: Insertion point is "^p", Retain text,
uncheck Strip returns. Voila!



Wave bye-bye...!

That's it, I think. This solves Kip's immediate problem in a way
that makes sense to me: I think both Kip and I are commited to
having all of the work done _before_ text is imported, so this
stands a fair chance of eliminating some delays from the process.
Moreover, it makes it possible to do generalized merging for any
data processing purpose. In conjunction with Torquemada, it makes a
formidable tool. When I finally get around to doing Shane the Plane
2.0, that will come into play, too, and I think Kip will have words
for all of us on how to use Shane, Caesura, Torquemada, ShawBerry
and other stuff to achieve some really impressive hands-off text
massage...



Very Best,



Greg Swann

CIS: 70640,1574

USPS: P.O. Box 1724
      Andover, MA 01810

1/23/93




THE INEVITABLE ADDENDUM REGARDING VERSION 1.0.1

Kip caught a nasty little logic error in version 1.0.0. I'm not
going to tell you what it was because it's so stupid it's
embarrassing (no grin). In any case, it's fixed in this version.
Because I don't like mere bug fix releases, I added a Preferences
menu alike unto Shane the Plane and Clip 'n' Save. When you Save
preferences, the switch settings and the Insertion point text are
saved. So if you have a default way of working, save the whole
thing as your prefs and they will come up with each launch.

(Res Edit Hacks only: you can have two sets of prefs like this: set
up one set and Save, Quit, from ResEdit copy the contents of PREF
129 into PREF 128, launch ShawBerry and set up another set of prefs
and Save again (which, of course, overwrites PREF 129); now the
first set is available from Restore defaults, and the second comes
up at launch time and when you Restore saved prefs; this general
procedure will work with any app of mine that has a Preferences
menu.)

1/26/93